home *** CD-ROM | disk | FTP | other *** search
/ Aminet 5 / Aminet 5 - March 1995.iso / Aminet / dev / gui / BGUI11B.lha / docs / externalclass.doc < prev    next >
Text File  |  1994-09-03  |  6KB  |  157 lines
  1.  
  2.            $RCSfile: externalclass.doc,v $
  3.         Description: Externalclass documentation.
  4.           Copyright: (C) Copyright 1994 Jaba Development.
  5.                      (C) Copyright 1994 Jan van den Baard.
  6.                      All Rights Reserved.
  7.  
  8.             $Author: jaba $
  9.           $Revision: 1.2 $
  10.               $Date: 1994/09/03 14:01:24 $
  11. ------------------------------------------------------------------------------
  12.  
  13. TABLE OF CONTENTS
  14.  
  15. externalclass/--background--
  16. externalclass/Methods
  17. externalclass/Attributes
  18.  
  19. externalclass/--background--                      externalclass/--background--
  20.  
  21.     NAME
  22.         Class:          externalclass
  23.         Superclass:     baseclass
  24.         Include File:   <libraries/bgui.h>
  25.  
  26.     FUNCTION
  27.         To provide an interface class which can be used to include third-party
  28.         gadget  classes  like  the colorwheel.gadget in a BGUI user interface.
  29.         Notification  is  currently only possible via the WM_ADDUPDATE method.
  30.         See  the  windowclass  documentation  for  more  information  on  this
  31.         subject.
  32.  
  33. externalclass/Methods                                    externalclass/Methods
  34.  
  35.     NEW METHODS
  36.         None.
  37.  
  38.     CHANGED METHODS
  39.         None.
  40.  
  41. externalclass/Attributes                              externalclass/Attributes
  42.  
  43.     NAME
  44.         EXT_Class -- ( Class * ), EXT_ClassID -- ( STRPTR )
  45.  
  46.     FUNCTION
  47.         Set  the  class  from  which this class needs to create an object. The
  48.         EXT_Class attribute expects a pointer to an already initialized class.
  49.         The EXT_ClassID expects the name of the public class like for instance
  50.         "colorwheel.gadget".  Please  note  that  _you_  are  responsible  for
  51.         opening and closing the class library yourself.
  52.  
  53.         Default NULL. Applicability is (I).
  54.  
  55.     NAME
  56.         EXT_MinWidth, EXT_MinHeight -- ( ULONG )
  57.  
  58.     FUNCTION
  59.         As  external  classes  normally  do  not  understand the layout engine
  60.         methods  used  by  BGUI  it  has  to  be  helped  a little. With these
  61.         attributes  you  set  the  minimum  width  and  height of the external
  62.         object.  It is very important to set reasonable values here because no
  63.         checks are made.
  64.  
  65.         Default is 0 (stupid size). Applicabilty is (I).
  66.  
  67.     NAME
  68.         EXT_TrackAttr -- ( Tag )
  69.  
  70.     FUNCTION
  71.         To  tell which attributes from the external object need to be tracked.
  72.         Because some external classes, like the colorwheel, cannot change size
  73.         once  created  it  is necessary that the externalclass  re-creates the
  74.         object  at  each  size  change. As this usually means that the current
  75.         external  object  settings are lost you can tell which attributes need
  76.         to be tracked.
  77.  
  78.         The  tracked  attributes are obtained by sending the external object a
  79.         OM_GET  method  for  each  of the attributes. This means that the only
  80.         attributes  that  can be tracked are the ones that are gettable on the
  81.         external object. There is no limit as to the number of attributes that
  82.         are trackable.
  83.  
  84.         You  can also pass attributes that are ment for the external object at
  85.         initialization time. These attributes are remembered by this class and
  86.         re-used at each re-creation of the external object.
  87.  
  88.         Example:
  89.  
  90.         Object          *wheel;
  91.         struct Screen   *screen;
  92.  
  93.         /*
  94.         **      Create a "colorwheel.gadget" external object.
  95.         **/
  96.         wheel = ExternalObject,
  97.                 EXT_MinWidth,                   30,
  98.                 EXT_MinHeight,                  30,
  99.                 EXT_ClassID,                    "colorwheel.gadget",
  100.                 WHEEL_Saturation,               0,
  101.                 WHEEL_Screen,                   screen,
  102.                 EXT_TrackAttr,                  WHEEL_Saturation,
  103.                 EXT_TrackAttr,                  WHEEL_Hue,
  104.         EndObject;
  105.  
  106.         All   tags   defined  above  are  saved  (including  the  tags  passed
  107.         automatically by the ExternalObject macro). Now a seperate copy of the
  108.         attributes to track is created.
  109.  
  110.         Once  the object needs to be re-created the  first  thing what is done
  111.         is getting the tracked attributes values from the old object.
  112.  
  113.         Now  the  old  object  is  disposed  of  and a new one is created with
  114.         exactly the same attributes that where passed at initialization time.
  115.  
  116.         Once  this  is  accomplished the tracked attributes are set to the new
  117.         object.
  118.  
  119.         Please note that tracking attributes  is only  necessary with  classes
  120.         that require a rebuild of the object when it is resized.
  121.  
  122.         Applicability is (I).
  123.  
  124.     BUGS
  125.         The  EXT_xxx  attributes from the initialization tags are not filtered
  126.         out of the saved tag list.
  127.  
  128.     SEE ALSO
  129.         EXT_NoRebuild
  130.  
  131.     NAME
  132.         EXT_Object -- ( Object * )
  133.  
  134.     FUNCTION
  135.         Get  a  pointer  to  the "real" external object. Please note that this
  136.         pointer changes at every size change.
  137.  
  138.         Applicability is (G).
  139.  
  140.     NAME
  141.         EXT_NoRebuild -- ( BOOL )
  142.  
  143.     FUNCTION
  144.         To tell the external class that the external object  does not  have to
  145.         be rebuild after a re-size. Most classes are smart enough to  handle a
  146.         re-size  of the  object  themselves  but  there are  classes  like the
  147.         colorwheel.gadget that requires a rebuild uppon a size change.
  148.  
  149.         When this   attribute   is   set  to  TRUE the class will not re-build
  150.         the external  object  and  you  do  not  need to use the EXT_TrackAttr
  151.         attributes to handle the object settings.
  152.  
  153.         Default is FALSE. Applicability is (I).
  154.  
  155.     SEE ALSO
  156.         EXT_TrackAttr
  157.